home *** CD-ROM | disk | FTP | other *** search
iiiiffffllllEEEErrrrrrrroooorrrr((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllEEEErrrrrrrroooorrrr((((3333)))) NNNNAAAAMMMMEEEE iiiiffffllllEEEErrrrrrrroooorrrr,,,, iiiiffffllllEEEErrrrrrrroooorrrrVVVV,,,, iiiiffffllllGGGGeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr,,,, iiiiffffllllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr,,,, iiiiffffllllSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg,,,, iiiiffffllllMMMMaaaaiiiinnnnSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg,,,, iiiiffffllllSSSSttttaaaattttuuuussssEEEEnnnnccccooooddddeeee - error handling SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS #include <ifl/iflError.h> void iflError(int flags, const char* fmt, ...) void iflErrorV(int flags, const char* fmt, va_list ap) void iflGetErrorHandler(iflErrorHandlerType* handler, void** arg) void iflSetErrorHandler(iflErrorHandlerType newhandler, void* newarg) char* iflStatusToString(iflStatus status, char buf[], int bufsize) const char* iflMainStatusToString(iflMainStatus status) iflStatusEncode(unsigned int mainstatus, unsigned int subDomain = iflSubDomainNONE, unsigned int subStatus = 0) DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN These functions are used to report errors and control how those errors are handled in the IFL environment. These facilities can also be used to generate debugging messages. The routines are grouped into three functional areas: error reporting, error handling, and status code translation. EEEErrrrrrrroooorrrr RRRReeeeppppoooorrrrttttiiiinnnngggg Error messages can be generated with the iiiiffffllllEEEErrrrrrrroooorrrr() routine. The _f_l_a_g_s parameter can have one of the following values: MM_INFO informational message, many error handlers will just ignore the message; this is primarily intended for debugging messages MM_WARNING warning, most error handlers will return and allow the program to continue executing MM_ERROR error, some error handlers will abort (the default error handler will) MM_HALT fatal error, most error handlers will abort the program The _f_m_t parameter is treated as a pppprrrriiiinnnnttttffff() format string. The remaining parameters (if any) are used in the formatting process as dictated by the format string. The iiiiffffllllEEEErrrrrrrroooorrrrVVVV() routine is provided for situations where the variable arguments have already been packaged in the "va_list" argument, _a_p. See the stdarg(5) man page for more details on this mechanism. PPPPaaaaggggeeee 1111 iiiiffffllllEEEErrrrrrrroooorrrr((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllEEEErrrrrrrroooorrrr((((3333)))) HHHHaaaannnnddddlllliiiinnnngggg EEEErrrrrrrroooorrrrssss The handling of errors is controlled by iiiiffffllllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(). The error handler is specified by the _n_e_w_h_a_n_d_l_e_r parameter and will be passed the _n_e_w_a_r_g parameter as a user closure. The prototype for an error handling routine that could be passed as _n_e_w_h_a_n_d_l_e_r is: handler(void* closureArg, int flags, const char* fmt, va_list ap) where the _c_l_o_s_u_r_e_A_r_g corresponds to the _n_e_w_a_r_g parameter of iiiiffffllllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr() and the _f_l_a_g_s, _f_m_t and _a_p parameters are as described for _i_f_l_E_r_r_o_r_V(). It is up to the error handler to decide whether or not to output a message and whether or not to abort based on the value of _f_l_a_g_s. The user may choose to supply their own error handler or use one of three built-in error handlers supplied with IL: iflNaiveErrorHandler this handler will abort on errors or fatal errors, it ignores informational messages; this is the default handler iflRobustErrorHandler this handler will only abort on fatal errors, it ignores informational messages iflSilentErrorHandler this handler will ignore all but fatal errors, which will be printed and cause the program to exit. TTTTrrrraaaannnnssssllllaaaattttiiiinnnngggg EEEErrrrrrrroooorrrr SSSSttttaaaattttuuuussss CCCCooooddddeeeessss Errors are encoded via the iflStatus type. There are three components of an iflStatus code: unsigned int mainstatus:12 IFL status code unsigned int subDomain:4 domain of subStatus unsigned int subStatus:16 subdomain status code _m_a_i_n_s_t_a_t_u_s encodes a main status code; _s_u_b_S_t_a_t_u_s encodes an elaboration of the main status code from another domain. For example: _m_a_i_n_s_t_a_t_u_s might be iflOPENFAILED and _s_u_b_S_t_a_t_u_s might be ENOFILE to indicate why IL returned iflOPENFAILED. In order to determine what _s_u_b_S_t_a_t_u_s means one must examine _s_u_b_d_o_m_a_i_n to see whether _s_u_b_S_t_a_t_u_s contains UNIX errno's, etc. The completely 0 status code, iflOKAY, is reserved. This makes it easier for most cases in which the caller does not care about the specific value, but only wants to compare with iflOKAY. PPPPaaaaggggeeee 2222 iiiiffffllllEEEErrrrrrrroooorrrr((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllEEEErrrrrrrroooorrrr((((3333)))) These fields of the iflStatus type can be picked apart with the iiiiffffllllGGGGeeeettttMMMMaaaaiiiinnnnSSSSttttaaaattttuuuussss(), iiiiffffllllGGGGeeeettttSSSSuuuubbbbDDDDoooommmmaaaaiiiinnnn() and iiiiffffllllGGGGeeeettttSSSSuuuubbbbSSSSttttaaaattttuuuussss() macros defined in <ifl/iflError.h>. The iflMainStatus enumerated type used for IL generated errors can be translated to a string using the iiiiffffllllMMMMaaaaiiiinnnnSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg() routine. An encoded iflStatus value can be converted to a string using iiiiffffllllSSSSttttaaaattttuuuussssTTTTooooSSSSttttrrrriiiinnnngggg(). The message will be converted into the user's buffer, _b_u_f, and truncated to _b_u_f_s_i_z_e characters in length if necessary. An iflMainStatus with optional sub-domain and sub-status is encoded into an iflStatus value by using the iiiiffffllllSSSSttttaaaattttuuuussssEEEEnnnnccccooooddddeeee() function. PPPPaaaaggggeeee 3333 
